 /*******************************************************************************
  * Copyright (c) 2005, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.ui.internal.provisional.cheatsheets;

 import org.eclipse.jface.viewers.ISelection;
 import org.eclipse.jface.viewers.ISelectionProvider;
 import org.eclipse.swt.widgets.Composite;
 import org.eclipse.swt.widgets.Control;
 import org.eclipse.ui.forms.widgets.FormToolkit;

 /**
  * Classes that extend this class are responsible for rendering the
  * hierarchy of tasks in the composite cheat sheet. They must support task
  * selection via the selection provider, be able to accept focus, and create
  * control when asked.
  */

 public abstract class TaskExplorer {
     /**
      * @return the id of this TaskExplorer which must match the id used in the
      * extension point
      */
     public abstract String getId();

     /**
      * Create a control which will display the structure of the composite cheat
      * sheet and allow tasks within the composite cheat sheet to be selected.
      *
      * @param parent
      * @param toolkit
      */
     public abstract void createControl(Composite parent, FormToolkit toolkit);

     /**
      * Get the control created by a previous call to createControl
      *
      * @return the task explorer control
      */
     public abstract Control getControl();

     /**
      * Called when the explorer gains focus.
      */
     public abstract void setFocus();

     /**
      * Get the selection provider for this explorer. The selections returned by
      * the selection provider should represent IGuideTasks.
      *
      * @return the selection provider for the task explorer
      */
     public abstract ISelectionProvider getSelectionProvider();

     /**
      * Sets the composite cheat sheet to be displayed. createControl will
      * already have been called.
      *
      * @param compositeCheatSheet
      */
     public abstract void setCompositeCheatSheet(ICompositeCheatSheet compositeCheatSheet);

     /**
      * Called after this explorer is no longer in use. Any resources should be
      * disposed of at this point.
      */
     public abstract void dispose();

     /**
      * Called when the state of a task changes and the representation of the
      * task may need to be redrawn.
      *
      * @param task
      */
     public abstract void taskUpdated(ICompositeCheatSheetTask task);

     /**
      * Called to set the provided selection and optionally reveal it
      * if the scroll bars are active and the selected tasks
      * are partially or fully hidden.
      *
      * @param selection the new selection
      * @param reveal if <code>true</code>, expose the task if hidden;
      * otherwise, just select.
      */
     public abstract void setSelection(ISelection selection, boolean reveal);
 }

